home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 19 / Amiga Format CD19 (1997-10-02)(Future Publishing)(GB)(Track 1 of 5)[!][issue 1997-11].iso / -seriously_amiga- / shareware / misc / virtualmem / autodocs / virtualmem.doc
Text File  |  1997-08-18  |  8KB  |  334 lines
  1. TABLE OF CONTENTS
  2.  
  3. virtualmem.library/AutoAdjustPri
  4. virtualmem.library/ChangeVMemPri
  5. virtualmem.library/CreateVMem
  6. virtualmem.library/FlushVMem
  7. virtualmem.library/GetVMemInfo
  8. virtualmem.library/LockVMem
  9. virtualmem.library/MakeVMem
  10. virtualmem.library/PageIn
  11. virtualmem.library/PageOut
  12. virtualmem.library/RemoveVMem
  13. virtualmem.library/SetVMemFlags
  14. virtualmem.library/UnlockVMem
  15. virtualmem.library/AutoAdjustPri             virtualmem.library/AutoAdjustPri
  16.  
  17.    NAME
  18.     AutoAdjustPri -- Adjust object priorities (V2)
  19.  
  20.    SYNOPSIS
  21.     AutoAdjustPri(array);
  22.                   a0
  23.  
  24.     VOID AutoAdjustPri(APTR *);
  25.  
  26.    FUNCTION
  27.     Automagically adjusts object priorities so that array[42] will get
  28.     paged out before array[6]. This call can increase the speed of
  29.     programs that process large amounts of data significantly.
  30.  
  31.    INPUTS
  32.     array - A NULL-terminated array of object handles
  33.  
  34.    BUGS
  35.     For now, you can't pass more than 255 object handles to
  36.     AutoAdjustPri().
  37.  
  38.    NOTE
  39.     The adjusting code is not quite optimal right now, as it just
  40.     distributes the memory objects evenly around 0.
  41.  
  42.    SEE ALSO
  43.     ChangeVMemPri
  44.  
  45. virtualmem.library/ChangeVMemPri             virtualmem.library/ChangeVMemPri
  46.  
  47.    NAME
  48.     ChangeVMemPri -- Change memory object priority
  49.  
  50.    SYNOPSIS
  51.     ChangeVMemPri(handle,newpri);
  52.  
  53.     VOID ChangeVMemPri(APTR,LONG);
  54.                        a0   d0-0:8
  55.  
  56.    FUNCTION
  57.     This function will change the priority of a memory object. The
  58.     lower the priority of a memory object is, the sooner it will be
  59.     paged out to disk.
  60.  
  61.    INPUTS
  62.     handle - A memory object handle
  63.     newpri - The new priority for the memory object
  64.  
  65.    SEE ALSO
  66.     CreateVMem
  67.  
  68. virtualmem.library/CreateVMem                   virtualmem.library/CreateVMem
  69.  
  70.    NAME
  71.     CreateVMem -- Create a memory object
  72.  
  73.    SYNOPSIS
  74.     handle = CreateVMem(size,flags,priority,virtualflags);
  75.     d0                  d0   d1    d2       d3
  76.  
  77.     APTR CreateVMem(ULONG,ULONG,BYTE,ULONG);
  78.  
  79.    FUNCTION
  80.     Creates a memory object.
  81.  
  82.    INPUTS
  83.     size - Size of the requested memory block
  84.     flags - Memory flags as with most exec.library memory allocation
  85.         functions
  86.     priority - The initial priority for the memory object
  87.     virtualflags - Additional flags
  88.  
  89.    RETURN
  90.     A pointer to a memory object handle. The structure for this object
  91.     is private as it is subject to change in the future.
  92.  
  93.    SEE ALSO
  94.     RemoveVMem, LockVMem, UnlockVMem, libraries/virtualmem.h
  95.  
  96. virtualmem.library/FlushVMem                     virtualmem.library/FlushVMem
  97.  
  98.    NAME
  99.     FlushVMem -- Page a memory object to disk
  100.  
  101.    SYNOPSIS
  102.     success = FlushVMem(attrs);
  103.                         d1
  104.  
  105.     BOOL FlushVMem(ULONG);
  106.  
  107.    FUNCTION
  108.     Ask virtualmem.library to page one memory object to disk. The
  109.     function will page the low-priority objects not belonging to the
  110.     calling task to disk first.
  111.  
  112.    INPUTS
  113.     attrs - Memory attributes
  114.  
  115.    RESULT
  116.     success - TRUE if a memory object was paged out, FALSE otherwise
  117.  
  118.    NOTE
  119.     This function was implemented mainly for the AllocMem() patch to
  120.     allow non-virtualmem.library tasks to run in relative harmony with
  121.     those that use virtualmem.library.
  122.  
  123. virtualmem.library/GetVMemInfo                 virtualmem.library/GetVMemInfo
  124.  
  125.    NAME
  126.     GetVMemInfo -- Get information about objects
  127.  
  128.    SYNOPSIS
  129.     GetVMemInfo(info);
  130.                 a0
  131.  
  132.     VOID GetVMemInfo(struct VMemStat *);
  133.  
  134.    FUNCTION
  135.     Gather information about memory objects and fill a given structure
  136.     with it. This function is relatively slow when lots of objects have
  137.     been created as it has to walk down the list of memory objects.
  138.  
  139.    INPUTS
  140.     info - A pointer to a VMemStat structure
  141.  
  142. virtualmem.library/LockVMem                       virtualmem.library/LockVMem
  143.  
  144.    NAME
  145.     LockVMem -- Lock a memory object into memory
  146.  
  147.    SYNOPSIS
  148.     memory = LockVMem(handle);
  149.     d0                a0
  150.  
  151.     APTR LockVMem(APTR);
  152.  
  153.    FUNCTION
  154.     Locks a memory object into RAM and returns a pointer to it. This
  155.     memory can then be used like conventional memory.
  156.  
  157.    INPUTS
  158.     handle - The memory handle as given to you by CreateVMem
  159.  
  160.    RETURN
  161.     memory - A pointer to the memory area the object controls
  162.  
  163.    NOTE
  164.     You should, in general, keep as little memory blocks locked at the
  165.     same time. This way, if a non-virtualmem.library task needs more
  166.     memory, virtualmem.library can page some low-priority objects to
  167.     disk.
  168.  
  169.     All succesful calls to LockVMem should have matching calls to
  170.     UnlockVMem()!
  171.  
  172.    SEE ALSO
  173.     UnlockVMem
  174.  
  175. virtualmem.library/MakeVMem                       virtualmem.library/MakeVMem
  176.  
  177.    NAME
  178.     MakeVMem -- Turn a memory block into a memory object
  179.  
  180.    SYNOPSIS
  181.     handle = MakeVMem(memory,size,flags,virtualflags);
  182.     d0                a0     d0   d1    d3
  183.  
  184.     APTR MakeVMem(APTR,ULONG,ULONG,ULONG);
  185.  
  186.    FUNCTION
  187.     Create a memory object and place the memory block into its control.
  188.     The memory area must have been allocated with AllocMem(),
  189.     AllocVec() will not do.    After the function is called, all pointers to
  190.     the memory become invalid. The resulting memory object will be unlocked.
  191.  
  192.    INPUTS
  193.     memory - The memory area to convert
  194.     size - Size in bytes
  195.     flags - Set of bits as given to CreateVMem()
  196.     virtualflags - Set of bits as given to CreateVMem()
  197.  
  198.    RETURN
  199.     handle - A memory object handle or NULL if failed
  200.  
  201.    NOTE
  202.     You must not FreeMem() the memory area yourself! It is now a memory
  203.     object and must be freed with RemoveVMem()!
  204.  
  205.    SEE ALSO
  206.     ChangeVMemPri, CreateVMem, RemoveVMem
  207.  
  208. virtualmem.library/PageIn                           virtualmem.library/PageIn
  209.  
  210.    NAME
  211.     PageIn -- Load a memory object back into RAM
  212.  
  213.    SYNOPSIS
  214.     success = PageIn(handle);
  215.                      a0
  216.  
  217.     BOOL PageIn(APTR);
  218.  
  219.    FUNCTION
  220.     Loads a memory object back to RAM from disk if it has been paged
  221.     out.
  222.  
  223.    INPUTS
  224.     handle - The memory object handle
  225.  
  226.    RETURN
  227.     success - TRUE if read was successful, FALSE otherwise
  228.  
  229.    NOTE
  230.     As this function wasn't originally meant to be used by programs
  231.     other than virtualmem.library, you shouldn't use it.
  232.  
  233.    SEE ALSO
  234.     PageOut
  235.  
  236. virtualmem.library/PageOut                         virtualmem.library/PageOut
  237.  
  238.    NAME
  239.     PageOut -- Page a memory object to disk
  240.  
  241.    SYNOPSIS
  242.     success = PageOut(handle);
  243.                       a0
  244.  
  245.     BOOL PageOut(APTR);
  246.  
  247.    FUNCTION
  248.     Pages a memory object to disk if not there already.
  249.  
  250.    INPUTS
  251.     handle - The memory object handle
  252.  
  253.    RETURN
  254.     success - TRUE if write was successful, FALSE otherwise
  255.  
  256.    NOTE
  257.     As this function wasn't originally meant to be used by programs
  258.     other than virtualmem.library, you shouldn't use it.
  259.  
  260.    SEE ALSO
  261.     PageIn, LockVMem
  262.  
  263. virtualmem.library/RemoveVMem                   virtualmem.library/RemoveVMem
  264.  
  265.    NAME
  266.     RemoveVMem -- Remove a memory object
  267.  
  268.    SYNOPSIS
  269.     RemoveVMem(handle);
  270.                a0
  271.  
  272.     VOID RemoveVMem(APTR);
  273.  
  274.    FUNCTION
  275.     Removes a memory object previously allocated with CreateVMem().
  276.     The memory object must be unlocked.
  277.  
  278.    INPUTS
  279.     handle - The memory object you wish to get rid of
  280.  
  281.    SEE ALSO
  282.     CreateVMem()
  283.  
  284. virtualmem.library/SetVMemFlags               virtualmem.library/SetVMemFlags
  285.  
  286.    NAME
  287.     SetVMemFlags -- Set user-definable flags (V3)
  288.  
  289.    SYNOPSIS
  290.     oldflags = SetVMemFlags(handle, newflags);
  291.                             a0      d0
  292.  
  293.        ULONG SetVMemFlags(APTR,ULONG);
  294.  
  295.    FUNCTION
  296.     Sets the user-definable flags in a memory object.
  297.  
  298.    INPUTS
  299.     handle - a memory object handle
  300.     newflags - the new flags
  301.  
  302.    RESULT
  303.     oldflags - the old flags that just got replaced
  304.  
  305.    NOTE
  306.     You can't set some of the flags after a memory object is created.
  307.     You should be able to set all defined flags for now; this may
  308.     change in the future, however.
  309.  
  310.    SEE ALSO
  311.     CreateVMem, MakeVMem
  312.  
  313. virtualmem.library/UnlockVMem                   virtualmem.library/UnlockVMem
  314.  
  315.    NAME
  316.     UnlockVMem -- Unlock a memory object
  317.  
  318.    SYNOPSIS
  319.     UnlockVMem(handle);
  320.                a0
  321.  
  322.     VOID UnlockVMem(APTR);
  323.  
  324.    FUNCTION
  325.     Unlocks a memory object. All pointers to the memory obtained with
  326.     LockVMem() from this object become invalid.
  327.  
  328.    INPUTS
  329.     handle - The memory object handle
  330.  
  331.    SEE ALSO
  332.     LockVMem
  333.  
  334.